<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Documenting &mdash; The Logtalk Handbook v3.93.0-b01 documentation</title>
      <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d75fae25" />
      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=19f00094" />
      <link rel="stylesheet" type="text/css" href="../_static/css/custom.css?v=396eccfe" />

  
  <!--[if lt IE 9]>
    <script src="../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
        <script src="../_static/jquery.js?v=5d32c60e"></script>
        <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
        <script src="../_static/documentation_options.js?v=c8100655"></script>
        <script src="../_static/doctools.js?v=9a2dae69"></script>
        <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="../_static/js/theme.js"></script>
    <!-- begin favicon -->
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
    <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png" />
    <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png" />
    <link rel="manifest" href="/site.webmanifest" />
    <link rel="mask-icon" href="/safari-pinned-tab.svg" color="#5bbad5" />
    <meta name="msapplication-TileColor" content="#355b95" />
    <meta name="theme-color" content="#ffffff" />
    <!-- end favicon -->
    
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Debugging" href="debugging.html" />
    <link rel="prev" title="Term and goal expansion" href="expansion.html" />
   
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >

          
          
          <a href="../index.html" class="icon icon-home">
            The Logtalk Handbook
              <img src="../_static/logtalk.gif" class="logo" alt="Logo"/>
          </a>
              <div class="version">
                3.93.0
              </div>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
    
              <p class="caption" role="heading"><span class="caption-text">Contents</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="index.html">User Manual</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="declarative.html">Declarative object-oriented programming</a></li>
<li class="toctree-l2"><a class="reference internal" href="features.html">Main features</a></li>
<li class="toctree-l2"><a class="reference internal" href="nomenclature.html">Nomenclature</a></li>
<li class="toctree-l2"><a class="reference internal" href="messages.html">Messages</a></li>
<li class="toctree-l2"><a class="reference internal" href="objects.html">Objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="protocols.html">Protocols</a></li>
<li class="toctree-l2"><a class="reference internal" href="categories.html">Categories</a></li>
<li class="toctree-l2"><a class="reference internal" href="predicates.html">Predicates</a></li>
<li class="toctree-l2"><a class="reference internal" href="inheritance.html">Inheritance</a></li>
<li class="toctree-l2"><a class="reference internal" href="events.html">Event-driven programming</a></li>
<li class="toctree-l2"><a class="reference internal" href="threads.html">Multi-threading programming</a></li>
<li class="toctree-l2"><a class="reference internal" href="errors.html">Error handling</a></li>
<li class="toctree-l2"><a class="reference internal" href="reflection.html">Reflection</a></li>
<li class="toctree-l2"><a class="reference internal" href="programming.html">Writing and running applications</a></li>
<li class="toctree-l2"><a class="reference internal" href="printing.html">Printing messages and asking questions</a></li>
<li class="toctree-l2"><a class="reference internal" href="expansion.html">Term and goal expansion</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Documenting</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#entity-documenting-directives">Entity documenting directives</a></li>
<li class="toctree-l3"><a class="reference internal" href="#predicate-documenting-directives">Predicate documenting directives</a></li>
<li class="toctree-l3"><a class="reference internal" href="#describing-predicates">Describing predicates</a></li>
<li class="toctree-l3"><a class="reference internal" href="#documenting-predicate-exceptions">Documenting predicate exceptions</a></li>
<li class="toctree-l3"><a class="reference internal" href="#processing-and-viewing-documenting-files">Processing and viewing documenting files</a></li>
<li class="toctree-l3"><a class="reference internal" href="#inline-formatting-in-comments-text">Inline formatting in comments text</a></li>
<li class="toctree-l3"><a class="reference internal" href="#diagrams">Diagrams</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="debugging.html">Debugging</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance.html">Performance</a></li>
<li class="toctree-l2"><a class="reference internal" href="installing.html">Installing Logtalk</a></li>
<li class="toctree-l2"><a class="reference internal" href="migration.html">Prolog integration and migration</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../refman/index.html">Reference Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="../faq/index.html">FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="../devtools/index.html">Developer Tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../libraries/index.html">Libraries</a></li>
<li class="toctree-l1"><a class="reference internal" href="../ports/index.html">Ports</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contributions/index.html">Contributions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
<li class="toctree-l1"><a class="reference internal" href="../bibliography.html">Bibliography</a></li>
<li class="toctree-l1"><a class="reference internal" href="../genindex.html">Index</a></li>
</ul>

    <p class="caption"><span class="caption-text">External Contents</span></p>
    <ul>
    <li class="toctree-l1"><a class="reference internal" href="../../apis/index.html">APIs</a></li>
    <li class="toctree-l1"><a class="reference internal" href="https://logtalk.org">Logtalk website</a></li>
    <li class="toctree-l1"><a class="reference internal" href="https://github.com/LogtalkDotOrg/logtalk3">GitHub repo</a></li>
    </ul>
  
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../index.html">The Logtalk Handbook</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
          <li class="breadcrumb-item"><a href="index.html">User Manual</a></li>
      <li class="breadcrumb-item active">Documenting</li>
      <li class="wy-breadcrumbs-aside">
              <a href="https://github.com/LogtalkDotOrg/logtalk3/blob/master/docs/handbook/sources/userman/documenting.rst" class="fa fa-github"> Edit on GitHub</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section id="documenting">
<span id="documenting-documenting"></span><h1>Documenting<a class="headerlink" href="#documenting" title="Link to this heading"></a></h1>
<p>Assuming that the <a class="reference internal" href="programming.html#flag-source-data"><span class="std std-ref">source_data</span></a> flag is turned on, the
compiler saves all relevant documenting information collected when compiling
a source file. The provided <a class="reference internal" href="../devtools/lgtdoc.html"><span class="doc">lgtdoc</span></a> tool can access this
information by using the <a class="reference internal" href="reflection.html#reflection-reflection"><span class="std std-ref">reflection</span></a> support
and generate a documentation file for each compiled entity (object, protocol,
or category) in XML format. Contents of the XML file include the entity name,
type, and compilation mode (static or dynamic), the entity relations with
other entities, and a description of any declared predicates (name,
compilation mode, scope, …). The XML documentation files can be enriched
with arbitrary user-defined information, either about an entity or about its
predicates, by using documentation directives. The <code class="docutils literal notranslate"><span class="pre">lgtdoc</span></code> tool includes
POSIX and Windows scripts for converting the XML documentation files to
several final formats (such as HTML and PDF).</p>
<p>Logtalk supports two documentation directives for providing arbitrary
user-defined information about an entity or a predicate. These two
directives complement other directives that also provide important
documentation information, such as the <a class="reference internal" href="../refman/directives/mode_2.html#directives-mode-2"><span class="std std-ref">mode/2</span></a> and
<a class="reference internal" href="../refman/directives/meta_predicate_1.html#directives-meta-predicate-1"><span class="std std-ref">meta_predicate/1</span></a> directives.</p>
<section id="entity-documenting-directives">
<span id="documenting-entity"></span><h2>Entity documenting directives<a class="headerlink" href="#entity-documenting-directives" title="Link to this heading"></a></h2>
<p>Arbitrary user-defined entity information can be represented using the
<a class="reference internal" href="../refman/directives/info_1.html#directives-info-1"><span class="std std-ref">info/1</span></a> directive:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">info</span>([
    <span class="nv">Key1</span> <span class="k">is</span> <span class="nv">Value1</span>,
    <span class="nv">Key2</span> <span class="k">is</span> <span class="nv">Value2</span>,
    ...
]).
</pre></div>
</div>
<p>In this pattern, keys should be atoms and values should be bound terms.
The following keys are predefined and may be processed specially by
Logtalk tools:</p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">comment</span></code></dt><dd><p>Comment describing the entity purpose (an atom). End the comment with a
period (full stop). As a style guideline, don’t use overly long comments.
If you need to provide additional details, use the <code class="docutils literal notranslate"><span class="pre">fails_if</span></code> and
<code class="docutils literal notranslate"><span class="pre">remarks</span></code> keys.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">author</span></code></dt><dd><p>Entity author(s) (an atom or a compound term <code class="docutils literal notranslate"><span class="pre">{entity}</span></code> where
<code class="docutils literal notranslate"><span class="pre">entity</span></code> is the name of an XML entity in a user-defined
<code class="docutils literal notranslate"><span class="pre">custom.ent</span></code> file).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">version</span></code></dt><dd><p>Version number (a <code class="docutils literal notranslate"><span class="pre">Major:Minor:Patch</span></code> compound term) Following the
<a class="reference external" href="https://semver.org">Semantic Versioning guidelines</a> is strongly advised.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">date</span></code></dt><dd><p>Date of last modification in ISO 8601 standard format (<code class="docutils literal notranslate"><span class="pre">Year-Month-Day</span></code>
where <code class="docutils literal notranslate"><span class="pre">Year</span></code>, <code class="docutils literal notranslate"><span class="pre">Month</span></code>, and <code class="docutils literal notranslate"><span class="pre">Day</span></code> are integers).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">parameters</span></code></dt><dd><p>Parameter names and descriptions for parametric entities (a list of
<code class="docutils literal notranslate"><span class="pre">Name-Description</span></code> pairs where both names and descriptions are atoms).
End the <code class="docutils literal notranslate"><span class="pre">Description</span></code> with a period (full stop).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">parnames</span></code></dt><dd><p>Parameter names for parametric entities (a list of atoms; a simpler
version of the previous key, used when parameter descriptions are
deemed unnecessary).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">copyright</span></code></dt><dd><p>Copyright notice for the entity source code (an atom or a compound
term <code class="docutils literal notranslate"><span class="pre">{entity}</span></code> where <code class="docutils literal notranslate"><span class="pre">entity</span></code> is the name of an XML entity
defined in a user-defined <code class="docutils literal notranslate"><span class="pre">custom.ent</span></code> file).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">license</span></code></dt><dd><p>License terms for the entity source code; usually, just the license
name (an atom or a compound term <code class="docutils literal notranslate"><span class="pre">{entity}</span></code> where <code class="docutils literal notranslate"><span class="pre">entity</span></code> is the
name of an XML entity in a user-defined <code class="docutils literal notranslate"><span class="pre">custom.ent</span></code> file). License
names should, whenever possible, be a license identifier as specified
in the <a class="reference external" href="https://spdx.org/licenses/">SPDX standard</a>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">remarks</span></code></dt><dd><p>List of general remarks about the entity using <code class="docutils literal notranslate"><span class="pre">Topic-Text</span></code> pairs
where both the topic and the text must be atoms. End the <code class="docutils literal notranslate"><span class="pre">Text</span></code>
with a period (full stop).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">see_also</span></code></dt><dd><p>List of related entities (using the entity identifiers, which can
be atoms or compound terms).</p>
</dd>
</dl>
<p>For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">info</span>([
    version <span class="k">is</span> <span class="m">2</span><span class="o">:</span><span class="m">1</span><span class="o">:</span><span class="m">0</span>,
    author <span class="k">is</span> <span class="s">&#39;Paulo Moura&#39;</span>,
    date <span class="k">is</span> <span class="m">2000</span><span class="o">-</span><span class="m">11</span><span class="o">-</span><span class="m">20</span>,
    comment <span class="k">is</span> <span class="s">&#39;Building representation.&#39;</span>,
    diagram <span class="k">is</span> <span class="s">&#39;UML Class Diagram #312&#39;</span>
]).
</pre></div>
</div>
<p>Use only the keywords that make sense for your application, and remember that
you are free to invent your own keywords. All key-value pairs can be retrieved
programmatically using the <a class="reference internal" href="reflection.html#reflection-reflection"><span class="std std-ref">reflection API</span></a> and
are visible to the <a class="reference internal" href="../devtools/lgtdoc.html"><span class="doc">lgtdoc</span></a> tool (which includes them in the
generated documentation).</p>
</section>
<section id="predicate-documenting-directives">
<span id="documenting-predicate"></span><h2>Predicate documenting directives<a class="headerlink" href="#predicate-documenting-directives" title="Link to this heading"></a></h2>
<p>Arbitrary user-defined predicate information can be represented using
the <a class="reference internal" href="../refman/directives/info_2.html#directives-info-2"><span class="std std-ref">info/2</span></a> directive:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">info</span>(<span class="nv">Name</span><span class="o">/</span><span class="nv">Arity</span>, [
    <span class="nv">Key1</span> <span class="k">is</span> <span class="nv">Value1</span>,
    <span class="nv">Key2</span> <span class="k">is</span> <span class="nv">Value2</span>,
    ...
]).
</pre></div>
</div>
<p>The first argument can also a grammar rule non-terminal indicator,
<code class="docutils literal notranslate"><span class="pre">Name//Arity</span></code>. Keys should be atoms. Values should be bound terms.
The following keys are predefined and may be processed specially by
Logtalk tools:</p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">comment</span></code></dt><dd><p>Comment describing the predicate (or non-terminal) purpose (an atom).
End the comment with a period (full stop). As a style guideline, don’t
use overly long comments. If you need to provide additional details,
use the <code class="docutils literal notranslate"><span class="pre">remarks</span></code> key.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">fails_if</span></code></dt><dd><p>Comment describing failing conditions for the predicate. As a style
guideline, don’t use overly long comments. If you need to provide
additional details, use the <code class="docutils literal notranslate"><span class="pre">remarks</span></code> key.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">arguments</span></code></dt><dd><p>Names and descriptions of predicate arguments for pretty print output
(a list of <code class="docutils literal notranslate"><span class="pre">Name-Description</span></code> pairs where both names and descriptions
are atoms). End the <code class="docutils literal notranslate"><span class="pre">Description</span></code> with a period (full stop).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">argnames</span></code></dt><dd><p>Names of predicate arguments for pretty print output (a list of
atoms; a simpler version of the previous key, used when argument
descriptions are deemed unnecessary).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">allocation</span></code></dt><dd><p>Objects where we should define the predicate. Some possible values
are <code class="docutils literal notranslate"><span class="pre">container</span></code>, <code class="docutils literal notranslate"><span class="pre">descendants</span></code>, <code class="docutils literal notranslate"><span class="pre">instances</span></code>, <code class="docutils literal notranslate"><span class="pre">classes</span></code>,
<code class="docutils literal notranslate"><span class="pre">subclasses</span></code>, and <code class="docutils literal notranslate"><span class="pre">any</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">redefinition</span></code></dt><dd><p>Describes if a predicate is expected to be redefined and, if so,
in what way. Some possible values are <code class="docutils literal notranslate"><span class="pre">never</span></code>, <code class="docutils literal notranslate"><span class="pre">free</span></code>,
<code class="docutils literal notranslate"><span class="pre">specialize</span></code>, <code class="docutils literal notranslate"><span class="pre">call_super_first</span></code>, <code class="docutils literal notranslate"><span class="pre">call_super_last</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">exceptions</span></code></dt><dd><p>List of possible exceptions thrown by the predicate using
<code class="docutils literal notranslate"><span class="pre">Description-Exception</span></code> pairs. The description must be an
atom. The exception term must be a ground term.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">examples</span></code></dt><dd><p>List of typical predicate call examples using the format
<code class="docutils literal notranslate"><span class="pre">Description-Goal-Bindings</span></code>. The description must be an atom
with the goal term sharing variables with the bindings. The
variable bindings term uses the format <code class="docutils literal notranslate"><span class="pre">{Variable</span> <span class="pre">=</span> <span class="pre">Term,</span> <span class="pre">...}</span></code>.
When there are no variable bindings, the success or failure of
the predicate call should be represented by the terms <code class="docutils literal notranslate"><span class="pre">{true}</span></code>
or <code class="docutils literal notranslate"><span class="pre">{false}</span></code>, respectively (you can also use in alternative
the terms <code class="docutils literal notranslate"><span class="pre">{yes}</span></code> or <code class="docutils literal notranslate"><span class="pre">{no}</span></code>).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">remarks</span></code></dt><dd><p>List of general remarks about the predicate using <code class="docutils literal notranslate"><span class="pre">Topic-Text</span></code>
pairs where both the topic and the text must be atoms. End the
<code class="docutils literal notranslate"><span class="pre">Text</span></code> with a period (full stop).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">since</span></code></dt><dd><p>Version that added the predicate (<code class="docutils literal notranslate"><span class="pre">Major:Minor:Patch</span></code>).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">see_also</span></code></dt><dd><p>List of related predicates and non-terminals (using the predicate
and non-terminal indicators).</p>
</dd>
</dl>
<p>For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">info</span>(color<span class="o">/</span><span class="m">1</span>, [
    comment <span class="k">is</span> <span class="s">&#39;Table of defined colors.&#39;</span>,
    argnames <span class="k">is</span> [<span class="s">&#39;Color&#39;</span>],
    constraint <span class="k">is</span> <span class="s">&#39;Up to four visible colors allowed.&#39;</span>,
    examples <span class="k">is</span> [
       <span class="s">&#39;Check that the color blue is defined&#39;</span> <span class="o">-</span> color(blue) <span class="o">-</span> <span class="k">{true}</span>
    ]
]).
</pre></div>
</div>
<p>As with the <code class="docutils literal notranslate"><span class="pre">info/1</span></code> directive, use only the keywords that make sense
for your application and remember that you are free to invent your own
keywords. All key-value pairs can also be retrieved programmatically
using the <a class="reference internal" href="reflection.html#reflection-reflection"><span class="std std-ref">reflection API</span></a> and are visible
to the <a class="reference internal" href="../devtools/lgtdoc.html"><span class="doc">lgtdoc</span></a> tool (which includes them in the generated
documentation).</p>
</section>
<section id="describing-predicates">
<span id="documenting-descriptions"></span><h2>Describing predicates<a class="headerlink" href="#describing-predicates" title="Link to this heading"></a></h2>
<p>The value of the <code class="docutils literal notranslate"><span class="pre">comment</span></code> key, possibly extended with the <code class="docutils literal notranslate"><span class="pre">remarks</span></code> key,
should describe a predicate purpose and, when applicable, the circumstances
under which a call may fail. Descriptions should be consistent across library
and application APIs. Some guidelines:</p>
<p>1. When starting the description with a verb, use the <em>third-person singular
simple present form</em>. For example, write <code class="docutils literal notranslate"><span class="pre">'Runs</span> <span class="pre">...'</span></code>, <code class="docutils literal notranslate"><span class="pre">'Calls</span> <span class="pre">...'</span></code>,
<code class="docutils literal notranslate"><span class="pre">'Compares</span> <span class="pre">...'</span></code>, <code class="docutils literal notranslate"><span class="pre">'Parses</span> <span class="pre">...'</span></code>, <code class="docutils literal notranslate"><span class="pre">'Generates</span> <span class="pre">...'</span></code>, <code class="docutils literal notranslate"><span class="pre">'Converts</span> <span class="pre">...'</span></code>,
<code class="docutils literal notranslate"><span class="pre">'Creates</span> <span class="pre">...'</span></code>, <code class="docutils literal notranslate"><span class="pre">'Maps</span> <span class="pre">...'</span></code>, <code class="docutils literal notranslate"><span class="pre">'Merges</span> <span class="pre">...'</span></code>, <code class="docutils literal notranslate"><span class="pre">'Finds</span> <span class="pre">...'</span></code>, etc.</p>
<p>2. Predicates that are pure logical relations often have descriptions starting
with <code class="docutils literal notranslate"><span class="pre">'True</span> <span class="pre">iff</span> <span class="pre">...'</span></code> or <code class="docutils literal notranslate"><span class="pre">'True</span> <span class="pre">if</span> <span class="pre">...'</span></code>.</p>
<p>3. Predicates with multiple solutions often have descriptions starting with
<code class="docutils literal notranslate"><span class="pre">'Enumerates,</span> <span class="pre">by</span> <span class="pre">backtracking,</span> <span class="pre">all</span> <span class="pre">...'</span></code> or <code class="docutils literal notranslate"><span class="pre">'Enumerates,</span> <span class="pre">by</span> <span class="pre">backtracking,</span>
<span class="pre">the</span> <span class="pre">...'</span></code>.</p>
<p>4. Predicate call failure conditions often have descriptions with one or more
sentences starting with <code class="docutils literal notranslate"><span class="pre">'Fails</span> <span class="pre">when</span> <span class="pre">...'</span></code> or <code class="docutils literal notranslate"><span class="pre">'Fails</span> <span class="pre">if</span> <span class="pre">...'</span></code>.</p>
<p>If you’re not sure how best to describe a predicate, look for examples in the
Logtalk libraries and developer tools APIs documentation.</p>
</section>
<section id="documenting-predicate-exceptions">
<span id="documenting-exceptions"></span><h2>Documenting predicate exceptions<a class="headerlink" href="#documenting-predicate-exceptions" title="Link to this heading"></a></h2>
<p>As described above, the <code class="docutils literal notranslate"><span class="pre">info/2</span></code> predicate directive supports an
<code class="docutils literal notranslate"><span class="pre">exceptions</span></code> key that allows us to list all exceptions that may occur
when calling a predicate. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">info</span>(check_option<span class="o">/</span><span class="m">1</span>, [
    comment <span class="k">is</span> <span class="s">&#39;Succeeds if the option is valid. Throws an error otherwise.&#39;</span>,
    argnames <span class="k">is</span> [<span class="s">&#39;Option&#39;</span>],
    exceptions <span class="k">is</span> [
        <span class="s">&#39;``Option`` is a variable&#39;</span> <span class="o">-</span> <span class="k">instantiation_error</span>,
        <span class="s">&#39;``Option`` is neither a variable nor a compound term&#39;</span> <span class="o">-</span> <span class="k">type_error</span>(compound, <span class="s">&#39;Option&#39;</span>),
        <span class="s">&#39;``Option`` is a compound term but not a valid option&#39;</span> <span class="o">-</span> <span class="k">domain_error</span>(option, <span class="s">&#39;Option&#39;</span>)
    ]
]).
</pre></div>
</div>
<p>When possible, only standard exceptions should be used. See e.g. the
<a class="reference internal" href="../refman/methods/error_handling_methods.html#error-handling-methods"><span class="std std-ref">error handling methods</span></a> section for
a full list. The argument names should be the same as those provided
in the <code class="docutils literal notranslate"><span class="pre">arguments</span></code> or <code class="docutils literal notranslate"><span class="pre">argnames</span></code> keys. Exceptions are usually
listed starting with instantiation and uninstantiation errors,
followed by type errors, and then domain errors. These may then be
followed by permission, existence, evaluation, representation, or
resource errors.</p>
<p>For each exception, use of <em>controlled language</em> as found, e.g., in the
ISO Prolog Core standard and this Handbook is advised. Some examples:</p>
<dl>
<dt>Instantiation error when one or more arguments cannot be a variable</dt><dd><p><code class="docutils literal notranslate"><span class="pre">Argument</span></code> is a variable</p>
<p><code class="docutils literal notranslate"><span class="pre">Argument1</span></code> and <code class="docutils literal notranslate"><span class="pre">Argument2</span></code> are variables</p>
</dd>
<dt>Instantiation error when a closed list with bound elements is required</dt><dd><p><code class="docutils literal notranslate"><span class="pre">Argument</span></code> is a partial list or a list with an element <code class="docutils literal notranslate"><span class="pre">Element</span></code> which is a variable</p>
</dd>
<dt>Uninstantiation error when an argument is not a variable</dt><dd><p><code class="docutils literal notranslate"><span class="pre">Argument</span></code> is not a variable</p>
</dd>
<dt>Type error when an argument is not a variable but also not of the expected type</dt><dd><p><code class="docutils literal notranslate"><span class="pre">Argument</span></code> is neither a variable nor a TYPE</p>
<p><code class="docutils literal notranslate"><span class="pre">Argument</span></code> is neither a partial list nor a list</p>
</dd>
<dt>Type error when an element of a list is not a variable but is not of the expected type</dt><dd><p>An element <code class="docutils literal notranslate"><span class="pre">Element</span></code> of the <code class="docutils literal notranslate"><span class="pre">Argument</span></code> list is neither a variable nor a TYPE</p>
</dd>
<dt>Domain error when an argument is of the correct type but not in the expected domain</dt><dd><p><code class="docutils literal notranslate"><span class="pre">Argument</span></code> is a TYPE but not a valid DOMAIN</p>
<p><code class="docutils literal notranslate"><span class="pre">Argument</span></code> is an integer that is less than zero</p>
</dd>
<dt>Domain error when an element of a list is of the correct type but not in the expected domain</dt><dd><p>An element <code class="docutils literal notranslate"><span class="pre">Element</span></code> of the <code class="docutils literal notranslate"><span class="pre">Argument</span></code> list is a TYPE but not a valid DOMAIN</p>
</dd>
<dt>Existence error when an entity of a given kind does not exist</dt><dd><p>The KIND <code class="docutils literal notranslate"><span class="pre">Argument</span></code> does not exist</p>
</dd>
</dl>
<p>Other classes of errors have a less rigid style. In case of doubt,
look for examples in this Handbook, in the APIs documentation, and
in standard documents.</p>
</section>
<section id="processing-and-viewing-documenting-files">
<span id="documenting-processing"></span><h2>Processing and viewing documenting files<a class="headerlink" href="#processing-and-viewing-documenting-files" title="Link to this heading"></a></h2>
<p>The <a class="reference internal" href="../devtools/lgtdoc.html"><span class="doc">lgtdoc</span></a> tool generates an XML documenting file per
entity. It can also generate library, directory, entity, and predicate
indexes when documenting libraries and directories. For example, assuming
the default filename extensions, a <code class="docutils literal notranslate"><span class="pre">trace</span></code> object and a <code class="docutils literal notranslate"><span class="pre">sort(_)</span></code>
parametric object will result in <code class="docutils literal notranslate"><span class="pre">trace_0.xml</span></code> and <code class="docutils literal notranslate"><span class="pre">sort_1.xml</span></code> XML
files.</p>
<p>Each entity XML file contains references to two other files, an XML
specification file and a XSLT stylesheet file. The XML specification
file can be either a DTD file (<code class="docutils literal notranslate"><span class="pre">logtalk_entity.dtd</span></code>) or an XML Scheme
file (<code class="docutils literal notranslate"><span class="pre">logtalk_entity.xsd</span></code>). The XSLT stylesheet file is responsible
for converting the XML files to some desired format such as HTML or PDF.
The default names for the XML specification file and the XSL stylesheet
file are defined by the <a class="reference internal" href="../devtools/lgtdoc.html"><span class="doc">lgtdoc</span></a> tool but can be
overridden by passing a list of options to the tool predicates. The
<code class="docutils literal notranslate"><span class="pre">lgtdoc/xml</span></code> sub-directory in the Logtalk installation directory contains
the XML specification files described above, along with several sample XSL
stylesheet files and sample scripts for converting XML documenting files
to several formats (e.g., reStructuredText, Markdown, HTML, and PDF). For
example, assume that you want to generate the API documentation for the
<code class="docutils literal notranslate"><span class="pre">types</span></code> library:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- {types(loader)}.
....

| ?- {lgtdoc(loader)}.
....

| ?- lgtdoc::library(types).
...
</pre></div>
</div>
<p>The above queries will result in the creation of a <code class="docutils literal notranslate"><span class="pre">xml_docs</span></code> in your
current directory by default. Assuming that we want to generate
Sphinx-based documentation and that we are using a POSIX operating-system,
the next steps would be:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>xml_docs
$<span class="w"> </span>lgt2rst<span class="w"> </span>-s<span class="w"> </span>-m
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">lgt2rst</span></code> script will ask a few questions (project name, author,
version, …). After its completion, the generated HTML files will be
found in the <code class="docutils literal notranslate"><span class="pre">_build/html</span></code> directory by default:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>open<span class="w"> </span>_build/html/index.html
</pre></div>
</div>
<p>For Windows operating-systems, PowerShell scripts are available. For
example, assuming that we want to generate HTML documentation, we could
run in a PowerShell window:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>PS &gt; cd xml_docs
PS &gt; lgt2html.ps1 -p saxon
</pre></div>
</div>
<p>After completion, the generated HTML files will be found in the <code class="docutils literal notranslate"><span class="pre">xml_docs</span></code>
directory by default.</p>
<p>See the <code class="docutils literal notranslate"><span class="pre">NOTES</span></code> file in the tool directory for details, specially on the
XSLT processor dependencies. You may use the supplied sample files as a
starting point for generating the documentation of your Logtalk applications.</p>
<p>The Logtalk DTD file, <code class="docutils literal notranslate"><span class="pre">logtalk_entity.dtd</span></code>, contains a reference to a
user-customizable file, <code class="docutils literal notranslate"><span class="pre">custom.ent</span></code>, which declares XML entities for
source code author names, license terms, and copyright strings. After
editing the <code class="docutils literal notranslate"><span class="pre">custom.ent</span></code> file to reflect your personal data, you may
use the XML entities on <code class="docutils literal notranslate"><span class="pre">info/1</span></code> documenting directives. For example,
assuming that the XML entities are named <em>author</em>, <em>license</em>, and
<em>copyright</em> we may write:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">info</span>([
    version <span class="k">is</span> <span class="m">1</span><span class="o">:</span><span class="m">1</span><span class="o">:</span><span class="m">0</span>,
    author <span class="k">is</span> <span class="k">{</span>author<span class="k">}</span>,
    license <span class="k">is</span> <span class="k">{</span>license<span class="k">}</span>,
    copyright <span class="k">is</span> <span class="k">{</span>copyright<span class="k">}</span>
]).
</pre></div>
</div>
<p>The entity references are replaced by the value of the corresponding XML
entity when the XML documenting files are processed (<strong>not</strong> when they
are generated; this notation is just a shortcut to take advantage of XML
entities).</p>
<p>The <a class="reference internal" href="../devtools/lgtdoc.html"><span class="doc">lgtdoc</span></a> tool supports a set of options that can be
used to control the generation of the XML documentation files. See the
tool documentation for details. There is also a <a class="reference internal" href="../devtools/doclet.html"><span class="doc">doclet</span></a>
tool that allows automating the steps required to generate the documentation
for an application.</p>
</section>
<section id="inline-formatting-in-comments-text">
<span id="documenting-formatting"></span><h2>Inline formatting in comments text<a class="headerlink" href="#inline-formatting-in-comments-text" title="Link to this heading"></a></h2>
<p>Inline formatting in comments text can be accomplished by using Markdown
or reStructuredText syntax and converting XML documenting files to Markdown
or reStructuredText files (and these, if required, to e.g. HTML, ePub, or
PDF formats). Note that Markdown and reStructuredText common syntax elements
are enough for most API documentation:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Mark *italic text* with one asterisk.
Mark **bold text** with two asterisks.
Mark ``monospaced text`` with two backquotes.
</pre></div>
</div>
<p>Rendering this block as markup gives:</p>
<blockquote>
<div><p>Mark <em>italic text</em> with one asterisk. Mark <strong>bold text</strong> with
two asterisks. Mark <code class="docutils literal notranslate"><span class="pre">monospaced</span> <span class="pre">text</span></code> with two backquotes.</p>
</div></blockquote>
<p>As single backquotes have different purposes in Markdown (monospaced text)
and reStructuredText (domain- or application-dependent meaning), never use
them. This also avoids doubts if there’s an inline formatting typo in text
meant to be rendered as monospaced text (usually inline code fragments).</p>
</section>
<section id="diagrams">
<h2>Diagrams<a class="headerlink" href="#diagrams" title="Link to this heading"></a></h2>
<p>The <a class="reference internal" href="../devtools/diagrams.html"><span class="doc">diagrams</span></a> tool supports a wide range of diagrams that
can also help in documenting an application. The generated diagrams can
include URL links to both source code and API documentation. They can also
be linked, connecting, for example, high level diagrams to detail diagrams.
These features allow diagrams to be an effective solution for navigating and
understanding the structure and implementation of an application. This tool
uses the same <a class="reference internal" href="reflection.html#reflection-reflection"><span class="std std-ref">reflection API</span></a> as the <code class="docutils literal notranslate"><span class="pre">lgtdoc</span></code>
tool and thus has access to the same source data. See the tool documentation
for details.</p>
</section>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="expansion.html" class="btn btn-neutral float-left" title="Term and goal expansion" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="debugging.html" class="btn btn-neutral float-right" title="Debugging" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 1998-2025, Paulo Moura.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>